XSLTProcess (Apache Ant API)

org.apache.tools.ant.taskdefs

## Class XSLTProcess

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.tools.ant.taskdefs.MatchingTask
      - - org.apache.tools.ant.taskdefs.XSLTProcess

- All Implemented Interfaces:
    java.lang.Cloneable, XSLTLogger, SelectorContainer

      public class XSLTProcess
      extends MatchingTask
      implements XSLTLogger

  Processes a set of XML documents via XSLT. This is useful for building views of XML based documentation.
  Since:
    Ant 1.1

- - ### Property Summary

    Properties
    Type | Property and Description
    --- | ---
    `XSLTProcess.OutputProperty` | `createOutput` Create an instance of an output property to be configured.

  - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `XSLTProcess.Factory` The factory element to configure a transformer factory
    `static class` | `XSLTProcess.OutputProperty` Specify how the result tree should be output as specified in the specification.
    `static class` | `XSLTProcess.Param` The Param inner class used to store XSL parameters
    `static class` | `XSLTProcess.ParamType` Enum for types of the parameter expression.
    `class` | `XSLTProcess.TraceConfiguration` Configuration for Xalan2 traces.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PROCESSOR_TRAX` The default processor is trax

    - ### Fields inherited from class org.apache.tools.ant.taskdefs.MatchingTask

      `fileset`

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XSLTProcess()` Creates a new XSLTProcess Task.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(FileNameMapper fileNameMapper)` Adds a nested filenamemapper.
    `void` | `add(ResourceCollection rc)` Adds a collection of resources to style in addition to the given file or the implicit fileset.
    `void` | `addConfiguredStyle(Resources rc)` Add a nested <style> element.
    `void` | `addConfiguredXMLCatalog(XMLCatalog xmlCatalog)` Add the catalog to our internal catalog
    `void` | `addMapper(Mapper mapper)` Defines the mapper to map source to destination files.
    `void` | `addSysproperty(Environment.Variable sysp)` A system property to set during transformation.
    `void` | `addSyspropertyset(PropertySet sysp)` A set of system properties to set during transformation.
    `protected void` | `configureLiaison(java.io.File stylesheet)` Deprecated. since Ant 1.7
    `protected void` | `configureLiaison(Resource stylesheet)` Loads the stylesheet and set xsl:param parameters.
    `Path` | `createClasspath()` Set the optional classpath to the XSL processor
    `XSLTProcess.Factory` | `createFactory()` Create the factory element to configure a trax liaison.
    `XSLTProcess.OutputProperty` | `createOutputProperty()` Create an instance of an output property to be configured.
    `XSLTProcess.Param` | `createParam()` Create an instance of an XSL parameter for configuration by Ant.
    `XSLTProcess.TraceConfiguration` | `createTrace()` Enables Xalan2 traces and uses the given configuration.
    `void` | `execute()` Executes the task.
    `XSLTProcess.Factory` | `getFactory()` Get the factory instance configured for this processor
    `protected XSLTLiaison` | `getLiaison()` Get the Liaison implementation to use in processing.
    `java.util.Enumeration` | `getOutputProperties()` Get an enumeration on the outputproperties.
    `boolean` | `getSuppressWarnings()` Whether to suppress warning messages of the processor.
    `XSLTProcess.TraceConfiguration` | `getTraceConfiguration()` Configuration for Xalan2 traces.
    `XMLCatalog` | `getXMLCatalog()` Get the XML catalog containing entity definitions
    `protected void` | `handleError(java.lang.String msg)` Throws an exception with the given message if failOnError is true, otherwise logs the message using the WARN level.
    `protected void` | `handleError(java.lang.Throwable ex)` Throws an exception with the given nested exception if failOnError is true, otherwise logs the message using the WARN level.
    `protected void` | `handleTransformationError(java.lang.Exception ex)` Throws an exception with the given nested exception if failOnError and failOnTransformationError are true, otherwise logs the message using the WARN level.
    `void` | `init()` Initialize internal instance of XMLCatalog.
    `void` | `setBasedir(java.io.File dir)` Set the base directory; optional, default is the project's basedir.
    `void` | `setClasspath(Path classpath)` Set the optional classpath to the XSL processor
    `void` | `setClasspathRef(Reference r)` Set the reference to an optional classpath to the XSL processor
    `void` | `setDestdir(java.io.File dir)` Set the destination directory into which the XSL result files should be copied to; required, unless `in` and `out` are specified.
    `void` | `setExtension(java.lang.String name)` Set the desired file extension to be used for the target; optional, default is html.
    `void` | `setFailOnError(boolean b)` Whether any errors should make the build fail.
    `void` | `setFailOnNoResources(boolean b)` Whether the build should fail if the nested resource collection is empty.
    `void` | `setFailOnTransformationError(boolean b)` Whether transformation errors should make the build fail.
    `void` | `setFileDirParameter(java.lang.String fileDirParameter)` Pass the directory name of the current processed file as a xsl parameter to the transformation.
    `void` | `setFileNameParameter(java.lang.String fileNameParameter)` Pass the filename of the current processed file as a xsl parameter to the transformation.
    `void` | `setForce(boolean force)` Set whether to check dependencies, or always generate; optional, default is false.
    `void` | `setIn(java.io.File inFile)` specifies a single XML document to be styled.
    `void` | `setOut(java.io.File outFile)` Specifies the output name for the styled result from the `in` attribute; required if `in` is set
    `void` | `setProcessor(java.lang.String processor)` Set the name of the XSL processor to use; optional, default trax.
    `void` | `setReloadStylesheet(boolean b)` Controls whether the stylesheet is reloaded for every transform.
    `void` | `setScanIncludedDirectories(boolean b)` Whether to style all files in the included directories as well; optional, default is true.
    `void` | `setStyle(java.lang.String xslFile)` Name of the stylesheet to use - given either relative to the project's basedir or as an absolute path; required.
    `void` | `setSuppressWarnings(boolean b)` Whether to suppress warning messages of the processor.
    `void` | `setUseImplicitFileset(boolean useimplicitfileset)` Whether to use the implicit fileset.
    `void` | `setXslResource(Resource xslResource)` API method to set the XSL Resource.

    - ### Methods inherited from class org.apache.tools.ant.taskdefs.MatchingTask

      `add, addAnd, addContains, addContainsRegexp, addCustom, addDate, addDepend, addDepth, addDifferent, addFilename, addMajority, addModified, addNone, addNot, addOr, addPresent, addSelector, addSize, addType, appendSelector, createExclude, createExcludesFile, createInclude, createIncludesFile, createPatternSet, getDirectoryScanner, getImplicitFileSet, getSelectors, hasSelectors, selectorCount, selectorElements, setCaseSensitive, setDefaultexcludes, setExcludes, setExcludesfile, setFollowSymlinks, setIncludes, setIncludesfile, setProject, XsetIgnore, XsetItems`

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.apache.tools.ant.taskdefs.XSLTLogger

      `log`

- - ### Property Detail

    - #### createOutput

      Create an instance of an output property to be configured.
      Returns:
        the newly created output property.
      Since:
        Ant 1.5

  - ### Field Detail

    - #### PROCESSOR_TRAX

          public static final java.lang.String PROCESSOR_TRAX

      The default processor is trax
      Since:
        Ant 1.7
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XSLTProcess

          public XSLTProcess()

      Creates a new XSLTProcess Task.

  - ### Method Detail

    - #### setScanIncludedDirectories

          public void setScanIncludedDirectories(boolean b)

      Whether to style all files in the included directories as well; optional, default is true.
      Parameters:
        `b` - true if files in included directories are processed.
      Since:
        Ant 1.5

    - #### setReloadStylesheet

          public void setReloadStylesheet(boolean b)

      Controls whether the stylesheet is reloaded for every transform.

      Setting this to true may get around a bug in certain Xalan-J versions, default is false.

      Parameters:
        `b` - a `boolean` value
      Since:
        Ant 1.5.2

    - #### addMapper

          public void addMapper(Mapper mapper)

      Defines the mapper to map source to destination files.
      Parameters:
        `mapper` - the mapper to use
      Throws:
        `BuildException` - if more than one mapper is defined
      Since:
        Ant 1.6.2

    - #### add

          public void add(ResourceCollection rc)

      Adds a collection of resources to style in addition to the given file or the implicit fileset.
      Parameters:
        `rc` - the collection of resources to style
      Since:
        Ant 1.7

    - #### addConfiguredStyle

          public void addConfiguredStyle(Resources rc)

      Add a nested <style> element.
      Parameters:
        `rc` - the configured Resources object represented as <style>.
      Since:
        Ant 1.7

    - #### setXslResource

          public void setXslResource(Resource xslResource)

      API method to set the XSL Resource.
      Parameters:
        `xslResource` - Resource to set as the stylesheet.
      Since:
        Ant 1.7

    - #### add

          public void add(FileNameMapper fileNameMapper)
                   throws BuildException

      Adds a nested filenamemapper.
      Parameters:
        `fileNameMapper` - the mapper to add
      Throws:
        `BuildException` - if more than one mapper is defined
      Since:
        Ant 1.7.0

    - #### execute

          public void execute()
                       throws BuildException

      Executes the task.
      Overrides:
        `execute` in class `Task`
      Throws:
        `BuildException` - if there is an execution problem.
      To do:
        validate that if either in or out is defined, then both are

    - #### setForce

          public void setForce(boolean force)

      Set whether to check dependencies, or always generate; optional, default is false.
      Parameters:
        `force` - true if always generate.

    - #### setBasedir

          public void setBasedir(java.io.File dir)

      Set the base directory; optional, default is the project's basedir.
      Parameters:
        `dir` - the base directory

    - #### setDestdir

          public void setDestdir(java.io.File dir)

      Set the destination directory into which the XSL result files should be copied to; required, unless `in` and `out` are specified.
      Parameters:
        `dir` - the name of the destination directory

    - #### setExtension

          public void setExtension(java.lang.String name)

      Set the desired file extension to be used for the target; optional, default is html.
      Parameters:
        `name` - the extension to use

    - #### setStyle

          public void setStyle(java.lang.String xslFile)

      Name of the stylesheet to use - given either relative to the project's basedir or as an absolute path; required.
      Parameters:
        `xslFile` - the stylesheet to use

    - #### setClasspath

          public void setClasspath(Path classpath)

      Set the optional classpath to the XSL processor
      Parameters:
        `classpath` - the classpath to use when loading the XSL processor

    - #### createClasspath

          public Path createClasspath()

      Set the optional classpath to the XSL processor
      Returns:
        a path instance to be configured by the Ant core.

    - #### setClasspathRef

          public void setClasspathRef(Reference r)

      Set the reference to an optional classpath to the XSL processor
      Parameters:
        `r` - the id of the Ant path instance to act as the classpath for loading the XSL processor

    - #### setProcessor

          public void setProcessor(java.lang.String processor)

      Set the name of the XSL processor to use; optional, default trax.
      Parameters:
        `processor` - the name of the XSL processor

    - #### setUseImplicitFileset

          public void setUseImplicitFileset(boolean useimplicitfileset)

      Whether to use the implicit fileset.

      Set this to false if you want explicit control with nested resource collections.

      Parameters:
        `useimplicitfileset` - set to true if you want to use implicit fileset
      Since:
        Ant 1.7

    - #### addConfiguredXMLCatalog

          public void addConfiguredXMLCatalog(XMLCatalog xmlCatalog)

      Add the catalog to our internal catalog
      Parameters:
        `xmlCatalog` - the XMLCatalog instance to use to look up DTDs

    - #### setFileNameParameter

          public void setFileNameParameter(java.lang.String fileNameParameter)

      Pass the filename of the current processed file as a xsl parameter to the transformation. This value sets the name of that xsl parameter.
      Parameters:
        `fileNameParameter` - name of the xsl parameter retrieving the current file name

    - #### setFileDirParameter

          public void setFileDirParameter(java.lang.String fileDirParameter)

      Pass the directory name of the current processed file as a xsl parameter to the transformation. This value sets the name of that xsl parameter.
      Parameters:
        `fileDirParameter` - name of the xsl parameter retrieving the current file directory

    - #### setSuppressWarnings

          public void setSuppressWarnings(boolean b)

      Whether to suppress warning messages of the processor.
      Since:
        Ant 1.8.0

    - #### getSuppressWarnings

          public boolean getSuppressWarnings()

      Whether to suppress warning messages of the processor.
      Since:
        Ant 1.8.0

    - #### setFailOnTransformationError

          public void setFailOnTransformationError(boolean b)

      Whether transformation errors should make the build fail.
      Since:
        Ant 1.8.0

    - #### setFailOnError

          public void setFailOnError(boolean b)

      Whether any errors should make the build fail.
      Since:
        Ant 1.8.0

    - #### setFailOnNoResources

          public void setFailOnNoResources(boolean b)

      Whether the build should fail if the nested resource collection is empty.
      Since:
        Ant 1.8.0

    - #### addSysproperty

          public void addSysproperty(Environment.Variable sysp)

      A system property to set during transformation.
      Since:
        Ant 1.8.0

    - #### addSyspropertyset

          public void addSyspropertyset(PropertySet sysp)

      A set of system properties to set during transformation.
      Since:
        Ant 1.8.0

    - #### createTrace

          public XSLTProcess.TraceConfiguration createTrace()

      Enables Xalan2 traces and uses the given configuration.

      Note that this element doesn't have any effect with a processor other than trax or if the Transformer is not Xalan2's transformer implementation.

      Since:
        Ant 1.8.0

    - #### getTraceConfiguration

          public XSLTProcess.TraceConfiguration getTraceConfiguration()

      Configuration for Xalan2 traces.
      Since:
        Ant 1.8.0

    - #### setOut

          public void setOut(java.io.File outFile)

      Specifies the output name for the styled result from the `in` attribute; required if `in` is set
      Parameters:
        `outFile` - the output File instance.

    - #### setIn

          public void setIn(java.io.File inFile)

      specifies a single XML document to be styled. Should be used with the `out` attribute; ; required if `out` is set
      Parameters:
        `inFile` - the input file

    - #### getFactory

          public XSLTProcess.Factory getFactory()

      Get the factory instance configured for this processor
      Returns:
        the factory instance in use

    - #### getXMLCatalog

          public XMLCatalog getXMLCatalog()

      Get the XML catalog containing entity definitions
      Returns:
        the XML catalog for the task.

    - #### getOutputProperties

          public java.util.Enumeration getOutputProperties()

      Get an enumeration on the outputproperties.
      Returns:
        the outputproperties

    - #### getLiaison

          protected XSLTLiaison getLiaison()

      Get the Liaison implementation to use in processing.
      Returns:
        an instance of the XSLTLiaison interface.

    - #### createParam

          public XSLTProcess.Param createParam()

      Create an instance of an XSL parameter for configuration by Ant.
      Returns:
        an instance of the Param class to be configured.

    - #### createOutputProperty

          public XSLTProcess.OutputProperty createOutputProperty()

      Create an instance of an output property to be configured.
      Returns:
        the newly created output property.
      Since:
        Ant 1.5

    - #### init

          public void init()
                    throws BuildException

      Initialize internal instance of XMLCatalog. Initialize XPath for parameter evaluation.
      Overrides:
        `init` in class `Task`
      Throws:
        `BuildException` - on error

    - #### configureLiaison

          @Deprecated
          protected void configureLiaison(java.io.File stylesheet)
                                   throws BuildException

      Deprecated. since Ant 1.7
      Loads the stylesheet and set xsl:param parameters.
      Parameters:
        `stylesheet` - the file from which to load the stylesheet.
      Throws:
        `BuildException` - if the stylesheet cannot be loaded.

    - #### configureLiaison

          protected void configureLiaison(Resource stylesheet)
                                   throws BuildException

      Loads the stylesheet and set xsl:param parameters.
      Parameters:
        `stylesheet` - the resource from which to load the stylesheet.
      Throws:
        `BuildException` - if the stylesheet cannot be loaded.
      Since:
        Ant 1.7

    - #### createFactory

          public XSLTProcess.Factory createFactory()
                                            throws BuildException

      Create the factory element to configure a trax liaison.
      Returns:
        the newly created factory element.
      Throws:
        `BuildException` - if the element is created more than one time.

    - #### handleError

          protected void handleError(java.lang.String msg)

      Throws an exception with the given message if failOnError is true, otherwise logs the message using the WARN level.
      Since:
        Ant 1.8.0

    - #### handleError

          protected void handleError(java.lang.Throwable ex)

      Throws an exception with the given nested exception if failOnError is true, otherwise logs the message using the WARN level.
      Since:
        Ant 1.8.0

    - #### handleTransformationError

          protected void handleTransformationError(java.lang.Exception ex)

      Throws an exception with the given nested exception if failOnError and failOnTransformationError are true, otherwise logs the message using the WARN level.
      Since:
        Ant 1.8.0